   This is an introduction to `Programming in Emacs Lisp', for people
who are not programmers.

   Edition 2.04, 2001 Dec 17

   Copyright (C) 1990, '91, '92, '93, '94, '95, '97, 2001 Free Software
Foundation, Inc.

   Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with the
Invariant Section being the Preface, with the Front-Cover Texts being
no Front-Cover Texts, and with the Back-Cover Texts being no Back-Cover
Texts.  A copy of the license is included in the section entitled "GNU
Free Documentation License".

Switching Buffers
=================

   The `other-buffer' function actually provides a buffer when it is
used as an argument to a function that requires one.  We can see this
by using `other-buffer' and `switch-to-buffer' to switch to a different
buffer.

   But first, a brief introduction to the `switch-to-buffer' function.
When you switched back and forth from Info to the `*scratch*' buffer to
evaluate `(buffer-name)', you most likely typed `C-x b' and then typed
`*scratch*'(1) when prompted in the minibuffer for the name of the
buffer to which you wanted to switch.  The keystrokes, `C-x b', cause
the Lisp interpreter to evaluate the interactive function
`switch-to-buffer'.  As we said before, this is how Emacs works:
different keystrokes call or run different functions.  For example,
`C-f' calls `forward-char', `M-e' calls `forward-sentence', and so on.

   By writing `switch-to-buffer' in an expression, and giving it a
buffer to switch to, we can switch buffers just the way `C-x b' does.

   Here is the Lisp expression:

     (switch-to-buffer (other-buffer))

The symbol `switch-to-buffer' is the first element of the list, so the
Lisp interpreter will treat it as a function and carry out the
instructions that are attached to it.  But before doing that, the
interpreter will note that `other-buffer' is inside parentheses and
work on that symbol first.  `other-buffer' is the first (and in this
case, the only) element of this list, so the Lisp interpreter calls or
runs the function.  It returns another buffer.  Next, the interpreter
runs `switch-to-buffer', passing to it, as an argument, the other
buffer, which is what Emacs will switch to.  If you are reading this in
Info, try this now.  Evaluate the expression.  (To get back, type `C-x
b <RET>'.)(2)

   In the programming examples in later sections of this document, you
will see the function `set-buffer' more often than `switch-to-buffer'.
This is because of a difference between computer programs and humans:
humans have eyes and expect to see the buffer on which they are working
on their computer terminals.  This is so obvious, it almost goes
without saying.  However, programs do not have eyes.  When a computer
program works on a buffer, that buffer does not need to be visible on
the screen.

   `switch-to-buffer' is designed for humans and does two different
things: it switches the buffer to which Emacs' attention is directed;
and it switches the buffer displayed in the window to the new buffer.
`set-buffer', on the other hand, does only one thing: it switches the
attention of the computer program to a different buffer.  The buffer on
the screen remains unchanged (of course, normally nothing happens there
until the command finishes running).

   Also, we have just introduced another jargon term, the word "call".
When you evaluate a list in which the first symbol is a function, you
are calling that function.  The use of the term comes from the notion of
the function as an entity that can do something for you if you `call'
it--just as a plumber is an entity who can fix a leak if you call him
or her.

   ---------- Footnotes ----------

   (1) Or rather, to save typing, you probably typed just part of the
name, such as `*sc', and then pressed your `TAB' key to cause it to
expand to the full name; and then typed your `RET' key.

   (2) Remember, this expression will move you to your most recent
other buffer that you cannot see.  If you really want to go to your
most recently selected buffer, even if you can still see it, you need
to evaluate the following more complex expression:

     (switch-to-buffer (other-buffer (current-buffer) t))

In this case, the first argument to `other-buffer' tells it which
buffer to skip--the current one--and the second argument tells
`other-buffer' it is OK to switch to a visible buffer.  In regular use,
`switch-to-buffer' takes you to an invisible window since you would
most likely use `C-x o' (`other-window') to go to another visible
buffer.

Buffer Size and the Location of Point
=====================================

   Finally, let's look at several rather simple functions,
`buffer-size', `point', `point-min', and `point-max'.  These give
information about the size of a buffer and the location of point within
it.

   The function `buffer-size' tells you the size of the current buffer;
that is, the function returns a count of the number of characters in
the buffer.

     (buffer-size)

You can evaluate this in the usual way, by positioning the cursor after
the expression and typing `C-x C-e'.

   In Emacs, the current  position of the cursor is called "point".
The expression `(point)' returns a number that tells you where the
cursor is located as a count of the number of characters from the
beginning of the buffer up to point.

   You can see the character count for point in this buffer by
evaluating the following expression in the usual way:

     (point)

As I write this, the value of `point' is 65724.  The `point' function
is frequently used in some of the examples later in this book.

   The value of point depends, of course, on its location within the
buffer.  If you evaluate point in this spot, the number will be larger:

     (point)

For me, the value of point in this location is 66043, which means that
there are 319 characters (including spaces) between the two expressions.

   The function `point-min' is somewhat similar to `point', but it
returns the value of the minimum permissible value of point in the
current buffer.  This is the number 1 unless "narrowing" is in effect.
(Narrowing is a mechanism whereby you can restrict yourself, or a
program, to operations on just a part of a buffer.  See Narrowing and Widening.)
Likewise, the function `point-max'
returns the value of the maximum permissible value of point in the
current buffer.

Exercise
========

   Find a file with which you are working and move towards its middle.
Find its buffer name, file name, length, and your position in the file.

How To Write Function Definitions
*********************************

   When the Lisp interpreter evaluates a list, it looks to see whether
the first symbol on the list has a function definition attached to it;
or, put another way, whether the symbol points to a function
definition.  If it does, the computer carries out the instructions in
the definition.  A symbol that has a function definition is called,
simply, a function (although, properly speaking, the definition is the
function and the symbol refers to it.)

An Aside about Primitive Functions
==================================

   All functions are defined in terms of other functions, except for a
few "primitive" functions that are written in the C programming
language.  When you write functions' definitions, you will write them in
Emacs Lisp and use other functions as your building blocks.  Some of the
functions you will use will themselves be written in Emacs Lisp (perhaps
by you) and some will be primitives written in C.  The primitive
functions are used exactly like those written in Emacs Lisp and behave
like them.  They are written in C so we can easily run GNU Emacs on any
computer that has sufficient power and can run C.

   Let me re-emphasize this: when you write code in Emacs Lisp, you do
not distinguish between the use of functions written in C and the use of
functions written in Emacs Lisp.  The difference is irrelevant.  I
mention the distinction only because it is interesting to know.  Indeed,
unless you investigate, you won't know whether an already-written
function is written in Emacs Lisp or C.

The `defun' Special Form
========================

   In Lisp, a symbol such as `mark-whole-buffer' has code attached to
it that tells the computer what to do when the function is called.
This code is called the "function definition" and is created by
evaluating a Lisp expression that starts with the symbol `defun' (which
is an abbreviation for _define function_).  Because `defun' does not
evaluate its arguments in the usual way, it is called a "special form".

   In subsequent sections, we will look at function definitions from the
Emacs source code, such as `mark-whole-buffer'.  In this section, we
will describe a simple function definition so you can see how it looks.
This function definition uses arithmetic because it makes for a simple
example.  Some people dislike examples using arithmetic; however, if
you are such a person, do not despair.  Hardly any of the code we will
study in the remainder of this introduction involves arithmetic or
mathematics.  The examples mostly involve text in one way or another.

   A function definition has up to five parts following the word
`defun':

  1. The name of the symbol to which the function definition should be
     attached.

  2. A list of the arguments that will be passed to the function.  If no
     arguments will be passed to the function, this is an empty list,
     `()'.

  3. Documentation describing the function.  (Technically optional, but
     strongly recommended.)

  4. Optionally, an expression to make the function interactive so you
     can use it by typing `M-x' and then the name of the function; or by
     typing an appropriate key or keychord.

  5. The code that instructs the computer what to do: the "body" of the
     function definition.

   It is helpful to think of the five parts of a function definition as
being organized in a template, with slots for each part:

     (defun FUNCTION-NAME (ARGUMENTS...)
       "OPTIONAL-DOCUMENTATION..."
       (interactive ARGUMENT-PASSING-INFO)     ; optional
       BODY...)

   As an example, here is the code for a function that multiplies its
argument by 7.  (This example is not interactive.  See Making a Function Interactive,
for that information.)

     (defun multiply-by-seven (number)
       "Multiply NUMBER by seven."
       (* 7 number))

   This definition begins with a parenthesis and the symbol `defun',
followed by the name of the function.

   The name of the function is followed by a list that contains the
arguments that will be passed to the function.  This list is called the
"argument list".  In this example, the list has only one element, the
symbol, `number'.  When the function is used, the symbol will be bound
to the value that is used as the argument to the function.

   Instead of choosing the word `number' for the name of the argument,
I could have picked any other name.  For example, I could have chosen
the word `multiplicand'.  I picked the word `number' because it tells
what kind of value is intended for this slot; but I could just as well
have chosen the word `multiplicand' to indicate the role that the value
placed in this slot will play in the workings of the function.  I could
have called it `foogle', but that would have been a bad choice because
it would not tell humans what it means.  The choice of name is up to
the programmer and should be chosen to make the meaning of the function
clear.

   Indeed, you can choose any name you wish for a symbol in an argument
list, even the name of a symbol used in some other function: the name
you use in an argument list is private to that particular definition.
In that definition, the name refers to a different entity than any use
of the same name outside the function definition.  Suppose you have a
nick-name `Shorty' in your family; when your family members refer to
`Shorty', they mean you.  But outside your family, in a movie, for
example, the name `Shorty' refers to someone else.  Because a name in an
argument list is private to the function definition, you can change the
value of such a symbol inside the body of a function without changing
its value outside the function.  The effect is similar to that produced
by a `let' expression.  (see `let'.)

   The argument list is followed by the documentation string that
describes the function.  This is what you see when you type `C-h f' and
the name of a function.  Incidentally, when you write a documentation
string like this, you should make the first line a complete sentence
since some commands, such as `apropos', print only the first line of a
multi-line documentation string.  Also, you should not indent the
second line of a documentation string, if you have one, because that
looks odd when you use `C-h f' (`describe-function').  The
documentation string is optional, but it is so useful, it should be
included in almost every function you write.

   The third line of the example consists of the body of the function
definition.  (Most functions' definitions, of course, are longer than
this.)  In this function, the body is the list, `(* 7 number)', which
says to multiply the value of NUMBER by 7.  (In Emacs Lisp, `*' is the
function for multiplication, just as `+' is the function for addition.)

   When you use the `multiply-by-seven' function, the argument `number'
evaluates to the actual number you want used.  Here is an example that
shows how `multiply-by-seven' is used; but don't try to evaluate this
yet!

     (multiply-by-seven 3)

The symbol `number', specified in the function definition in the next
section, is given or "bound to" the value 3 in the actual use of the
function.  Note that although `number' was inside parentheses in the
function definition, the argument passed to the `multiply-by-seven'
function is not in parentheses.  The parentheses are written in the
function definition so the computer can figure out where the argument
list ends and the rest of the function definition begins.

   If you evaluate this example, you are likely to get an error message.
(Go ahead, try it!)  This is because we have written the function
definition, but not yet told the computer about the definition--we have
not yet installed (or `loaded') the function definition in Emacs.
Installing a function is the process that tells the Lisp interpreter the
definition of the function.  Installation is described in the next
section.

Install a Function Definition
=============================

   If you are reading this inside of Info in Emacs, you can try out the
`multiply-by-seven' function by first evaluating the function
definition and then evaluating `(multiply-by-seven 3)'.  A copy of the
function definition follows.  Place the cursor after the last
parenthesis of the function definition and type `C-x C-e'.  When you do
this, `multiply-by-seven' will appear in the echo area.  (What this
means is that when a function definition is evaluated, the value it
returns is the name of the defined function.)  At the same time, this
action installs the function definition.

     (defun multiply-by-seven (number)
       "Multiply NUMBER by seven."
       (* 7 number))

By evaluating this `defun', you have just installed `multiply-by-seven'
in Emacs.  The function is now just as much a part of Emacs as
`forward-word' or any other editing function you use.
(`multiply-by-seven' will stay installed until you quit Emacs.  To
reload code automatically whenever you start Emacs, see
Installing Code Permanently.)

The effect of installation
--------------------------

   You can see the effect of installing `multiply-by-seven' by
evaluating the following sample.  Place the cursor after the following
expression and type `C-x C-e'.  The number 21 will appear in the echo
area.

     (multiply-by-seven 3)

   If you wish, you can read the documentation for the function by
typing `C-h f' (`describe-function') and then the name of the function,
`multiply-by-seven'.  When you do this, a `*Help*' window will appear
on your screen that says:

     multiply-by-seven:
     Multiply NUMBER by seven.

(To return to a single window on your screen, type `C-x 1'.)

Change a Function Definition
----------------------------

   If you want to change the code in `multiply-by-seven', just rewrite
it.  To install the new version in place of the old one, evaluate the
function definition again.  This is how you modify code in Emacs.  It is
very simple.

   As an example, you can change the `multiply-by-seven' function to
add the number to itself seven times instead of multiplying the number
by seven.  It produces the same answer, but by a different path.  At
the same time, we will add a comment to the code; a comment is text
that the Lisp interpreter ignores, but that a human reader may find
useful or enlightening.  The comment is that this is the "second
version".

     (defun multiply-by-seven (number)       ; Second version.
       "Multiply NUMBER by seven."
       (+ number number number number number number number))

   The comment follows a semicolon, `;'.  In Lisp, everything on a line
that follows a semicolon is a comment.  The end of the line is the end
of the comment.  To stretch a comment over two or more lines, begin
each line with a semicolon.

   See Beginning a `.emacs' File.emacs File, and
Comments (elisp), for more about comments.

   You can install this version of the `multiply-by-seven' function by
evaluating it in the same way you evaluated the first function: place
the cursor after the last parenthesis and type `C-x C-e'.

   In summary, this is how you write code in Emacs Lisp: you write a
function; install it; test it; and then make fixes or enhancements and
install it again.

Make a Function Interactive
===========================

   You make a function interactive by placing a list that begins with
the special form `interactive' immediately after the documentation.  A
user can invoke an interactive function by typing `M-x' and then the
name of the function; or by typing the keys to which it is bound, for
example, by typing `C-n' for `next-line' or `C-x h' for
`mark-whole-buffer'.

   Interestingly, when you call an interactive function interactively,
the value returned is not automatically displayed in the echo area.
This is because you often call an interactive function for its side
effects, such as moving forward by a word or line, and not for the
value returned.  If the returned value were displayed in the echo area
each time you typed a key, it would be very distracting.

An Interactive `multiply-by-seven', An Overview
-----------------------------------------------

   Both the use of the special form `interactive' and one way to
display a value in the echo area can be illustrated by creating an
interactive version of `multiply-by-seven'.

   Here is the code:

     (defun multiply-by-seven (number)       ; Interactive version.
       "Multiply NUMBER by seven."
       (interactive "p")
       (message "The result is %d" (* 7 number)))

You can install this code by placing your cursor after it and typing
`C-x C-e'.  The name of the function will appear in your echo area.
Then, you can use this code by typing `C-u' and a number and then
typing `M-x multiply-by-seven' and pressing <RET>.  The phrase `The
result is ...' followed by the product will appear in the echo area.

   Speaking more generally, you invoke a function like this in either
of two ways:

  1. By typing a prefix argument that contains the number to be passed,
     and then typing `M-x' and the name of the function, as with `C-u 3
     M-x forward-sentence'; or,

  2. By typing whatever key or keychord the function is bound to, as
     with `C-u 3 M-e'.

Both the examples just mentioned work identically to move point forward
three sentences.  (Since `multiply-by-seven' is not bound to a key, it
could not be used as an example of key binding.)

   (see Some Keybindings, to learn how to bind a command
to a key.)

   A prefix argument is passed to an interactive function by typing the
<META> key followed by a number, for example, `M-3 M-e', or by typing
`C-u' and then a number, for example, `C-u 3 M-e' (if you type `C-u'
without a number, it defaults to 4).

An Interactive `multiply-by-seven'
----------------------------------

   Let's look at the use of the special form `interactive' and then at
the function `message' in the interactive version of
`multiply-by-seven'.  You will recall that the function definition
looks like this:

     (defun multiply-by-seven (number)       ; Interactive version.
       "Multiply NUMBER by seven."
       (interactive "p")
       (message "The result is %d" (* 7 number)))

   In this function, the expression, `(interactive "p")', is a list of
two elements.  The `"p"' tells Emacs to pass the prefix argument to the
function and use its value for the argument of the function.

   The argument will be a number.  This means that the symbol `number'
will be bound to a number in the line:

     (message "The result is %d" (* 7 number))

For example, if your prefix argument is 5, the Lisp interpreter will
evaluate the line as if it were:

     (message "The result is %d" (* 7 5))

(If you are reading this in GNU Emacs, you can evaluate this expression
yourself.)  First, the interpreter will evaluate the inner list, which
is `(* 7 5)'.  This returns a value of 35.  Next, it will evaluate the
outer list, passing the values of the second and subsequent elements of
the list to the function `message'.

   As we have seen, `message' is an Emacs Lisp function especially
designed for sending a one line message to a user.  (see The `message' function.)
In summary, the `message' function
prints its first argument in the echo area as is, except for
occurrences of `%d', `%s', or `%c'.  When it sees one of these control
sequences, the function looks to the second and subsequent arguments
and prints the value of the argument in the location in the string
where the control sequence is located.

   In the interactive `multiply-by-seven' function, the control string
is `%d', which requires a number, and the value returned by evaluating
`(* 7 5)' is the number 35.  Consequently, the number 35 is printed in
place of the `%d' and the message is `The result is 35'.

   (Note that when you call the function `multiply-by-seven', the
message is printed without quotes, but when you call `message', the
text is printed in double quotes.  This is because the value returned by
`message' is what appears in the echo area when you evaluate an
expression whose first element is `message'; but when embedded in a
function, `message' prints the text as a side effect without quotes.)

Different Options for `interactive'
===================================

   In the example, `multiply-by-seven' used `"p"' as the argument to
`interactive'.  This argument told Emacs to interpret your typing
either `C-u' followed by a number or <META> followed by a number as a
command to pass that number to the function as its argument.  Emacs has
more than twenty characters predefined for use with `interactive'.  In
almost every case, one of these options will enable you to pass the
right information interactively to a function.  (see Code Characters for `interactive' (elisp).)

   For example, the character `r' causes Emacs to pass the beginning
and end of the region (the current values of point and mark) to the
function as two separate arguments.  It is used as follows:

     (interactive "r")

   On the other hand, a `B' tells Emacs to ask for the name of a buffer
that will be passed to the function.  When it sees a `B', Emacs will
ask for the name by prompting the user in the minibuffer, using a
string that follows the `B', as in `"BAppend to buffer: "'.  Not only
will Emacs prompt for the name, but Emacs will complete the name if you
type enough of it and press <TAB>.

   A function with two or more arguments can have information passed to
each argument by adding parts to the string that follows `interactive'.
When you do this, the information is passed to each argument in the
same order it is specified in the `interactive' list.  In the string,
each part is separated from the next part by a `\n', which is a
newline.  For example, you could follow `"BAppend to buffer: "' with a
`\n') and an `r'.  This would cause Emacs to pass the values of point
and mark to the function as well as prompt you for the buffer--three
arguments in all.

   In this case, the function definition would look like the following,
where `buffer', `start', and `end' are the symbols to which
`interactive' binds the buffer and the current values of the beginning
and ending of the region:

     (defun NAME-OF-FUNCTION (buffer start end)
       "DOCUMENTATION..."
       (interactive "BAppend to buffer: \nr")
       BODY-OF-FUNCTION...)

(The space after the colon in the prompt makes it look better when you
are prompted.  The `append-to-buffer' function looks exactly like this.
See The Definition of `append-to-buffer'.)

   If a function does not have arguments, then `interactive' does not
require any.  Such a function contains the simple expression
`(interactive)'.  The `mark-whole-buffer' function is like this.

   Alternatively, if the special letter-codes are not right for your
application, you can pass your own arguments to `interactive' as a
list.  See Using `Interactive' (elisp), for more
information about this advanced technique.

Install Code Permanently
========================

   When you install a function definition by evaluating it, it will stay
installed until you quit Emacs.  The next time you start a new session
of Emacs, the function will not be installed unless you evaluate the
function definition again.

   At some point, you may want to have code installed automatically
whenever you start a new session of Emacs.  There are several ways of
doing this:

   * If you have code that is just for yourself, you can put the code
     for the function definition in your `.emacs' initialization file.
     When you start Emacs, your `.emacs' file is automatically
     evaluated and all the function definitions within it are installed.
     See Your `.emacs' File.

   * Alternatively, you can put the function definitions that you want
     installed in one or more files of their own and use the `load'
     function to cause Emacs to evaluate and thereby install each of the
     functions in the files.  See Loading Files.

   * On the other hand, if you have code that your whole site will use,
     it is usual to put it in a file called `site-init.el' that is
     loaded when Emacs is built.  This makes the code available to
     everyone who uses your machine.  (See the `INSTALL' file that is
     part of the Emacs distribution.)

   Finally, if you have code that everyone who uses Emacs may want, you
can post it on a computer network or send a copy to the Free Software
Foundation.  (When you do this, please license the code and its
documentation under a license that permits other people to run, copy,
study, modify, and redistribute the code and which protects you from
having your work taken from you.)  If you send a copy of your code to
the Free Software Foundation, and properly protect yourself and others,
it may be included in the next release of Emacs.  In large part, this
is how Emacs has grown over the past years, by donations.

`let'
=====

   The `let' expression is a special form in Lisp that you will need to
use in most function definitions.

   `let' is used to attach or bind a symbol to a value in such a way
that the Lisp interpreter will not confuse the variable with a variable
of the same name that is not part of the function.

   To understand why the `let' special form is necessary, consider the
situation in which you own a home that you generally refer to as `the
house', as in the sentence, "The house needs painting."  If you are
visiting a friend and your host refers to `the house', he is likely to
be referring to _his_ house, not yours, that is, to a different house.

   If your friend is referring to his house and you think he is
referring to your house, you may be in for some confusion.  The same
thing could happen in Lisp if a variable that is used inside of one
function has the same name as a variable that is used inside of another
function, and the two are not intended to refer to the same value.  The
`let' special form prevents this kind of confusion.

`let' Prevents Confusion
------------------------

   The `let' special form prevents confusion.  `let' creates a name for
a "local variable" that overshadows any use of the same name outside
the `let' expression.  This is like understanding that whenever your
host refers to `the house', he means his house, not yours.  (Symbols
used in argument lists work the same way.  See The `defun' Special Form.)

   Local variables created by a `let' expression retain their value
_only_ within the `let' expression itself (and within expressions
called within the `let' expression); the local variables have no effect
outside the `let' expression.

   Another way to think about `let' is that it is like a `setq' that is
temporary and local.  The values set by `let' are automatically undone
when the `let' is finished.  The setting only effects expressions that
are inside the bounds of the `let' expression.  In computer science
jargon, we would say "the binding of a symbol is visible only in
functions called in the `let' form; in Emacs Lisp, scoping is dynamic,
not lexical."

   `let' can create more than one variable at once.  Also, `let' gives
each variable it creates an initial value, either a value specified by
you, or `nil'.  (In the jargon, this is called `binding the variable to
the value'.)  After `let' has created and bound the variables, it
executes the code in the body of the `let', and returns the value of
the last expression in the body, as the value of the whole `let'
expression.  (`Execute' is a jargon term that means to evaluate a list;
it comes from the use of the word meaning `to give practical effect to'
(`Oxford English Dictionary').  Since you evaluate an expression to
perform an action, `execute' has evolved as a synonym to `evaluate'.)

The Parts of a `let' Expression
-------------------------------

   A `let' expression is a list of three parts.  The first part is the
symbol `let'.  The second part is a list, called a "varlist", each
element of which is either a symbol by itself or a two-element list,
the first element of which is a symbol.  The third part of the `let'
expression is the body of the `let'.  The body usually consists of one
or more lists.

   A template for a `let' expression looks like this:

     (let VARLIST BODY...)

The symbols in the varlist are the variables that are given initial
values by the `let' special form.  Symbols by themselves are given the
initial value of `nil'; and each symbol that is the first element of a
two-element list is bound to the value that is returned when the Lisp
interpreter evaluates the second element.

   Thus, a varlist might look like this: `(thread (needles 3))'.  In
this case, in a `let' expression, Emacs binds the symbol `thread' to an
initial value of `nil', and binds the symbol `needles' to an initial
value of 3.

   When you write a `let' expression, what you do is put the
appropriate expressions in the slots of the `let' expression template.

   If the varlist is composed of two-element lists, as is often the
case, the template for the `let' expression looks like this:

     (let ((VARIABLE VALUE)
           (VARIABLE VALUE)
           ...)
       BODY...)

Sample `let' Expression
-----------------------

   The following expression creates and gives initial values to the two
variables `zebra' and `tiger'.  The body of the `let' expression is a
list which calls the `message' function.

     (let ((zebra 'stripes)
           (tiger 'fierce))
       (message "One kind of animal has %s and another is %s."
                zebra tiger))

   Here, the varlist is `((zebra 'stripes) (tiger 'fierce))'.

   The two variables are `zebra' and `tiger'.  Each variable is the
first element of a two-element list and each value is the second
element of its two-element list.  In the varlist, Emacs binds the
variable `zebra' to the value `stripes', and binds the variable `tiger'
to the value `fierce'.  In this example, both values are symbols
preceded by a quote.  The values could just as well have been another
list or a string.  The body of the `let' follows after the list holding
the variables.  In this example, the body is a list that uses the
`message' function to print a string in the echo area.

   You may evaluate the example in the usual fashion, by placing the
cursor after the last parenthesis and typing `C-x C-e'.  When you do
this, the following will appear in the echo area:

     "One kind of animal has stripes and another is fierce."

   As we have seen before, the `message' function prints its first
argument, except for `%s'.  In this example, the value of the variable
`zebra' is printed at the location of the first `%s' and the value of
the variable `tiger' is printed at the location of the second `%s'.

Uninitialized Variables in a `let' Statement
--------------------------------------------

   If you do not bind the variables in a `let' statement to specific
initial values, they will automatically be bound to an initial value of
`nil', as in the following expression:

     (let ((birch 3)
           pine
           fir
           (oak 'some))
       (message
        "Here are %d variables with %s, %s, and %s value."
        birch pine fir oak))

Here, the varlist is `((birch 3) pine fir (oak 'some))'.

   If you evaluate this expression in the usual way, the following will
appear in your echo area:

     "Here are 3 variables with nil, nil, and some value."

In this example, Emacs binds the symbol `birch' to the number 3, binds
the symbols `pine' and `fir' to `nil', and binds the symbol `oak' to
the value `some'.

   Note that in the first part of the `let', the variables `pine' and
`fir' stand alone as atoms that are not surrounded by parentheses; this
is because they are being bound to `nil', the empty list.  But `oak' is
bound to `some' and so is a part of the list `(oak 'some)'.  Similarly,
`birch' is bound to the number 3 and so is in a list with that number.
(Since a number evaluates to itself, the number does not need to be
quoted.  Also, the number is printed in the message using a `%d' rather
than a `%s'.)  The four variables as a group are put into a list to
delimit them from the body of the `let'.

The `if' Special Form
=====================

   A third special form, in addition to `defun' and `let', is the
conditional `if'.  This form is used to instruct the computer to make
decisions.  You can write function definitions without using `if', but
it is used often enough, and is important enough, to be included here.
It is used, for example, in the code for the function
`beginning-of-buffer'.

   The basic idea behind an `if', is that "_if_ a test is true, _then_
an expression is evaluated."  If the test is not true, the expression
is not evaluated.  For example, you might make a decision such as, "if
it is warm and sunny, then go to the beach!"

`if' in more detail
-------------------

   An `if' expression written in Lisp does not use the word `then'; the
test and the action are the second and third elements of the list whose
first element is `if'.  Nonetheless, the test part of an `if'
expression is often called the "if-part" and the second argument is
often called the "then-part".

   Also, when an `if' expression is written, the true-or-false-test is
usually written on the same line as the symbol `if', but the action to
carry out if the test is true, the "then-part", is written on the
second and subsequent lines.  This makes the `if' expression easier to
read.

     (if TRUE-OR-FALSE-TEST
         ACTION-TO-CARRY-OUT-IF-TEST-IS-TRUE)

The true-or-false-test will be an expression that is evaluated by the
Lisp interpreter.

   Here is an example that you can evaluate in the usual manner.  The
test is whether the number 5 is greater than the number 4.  Since it
is, the message `5 is greater than 4!' will be printed.

     (if (> 5 4)                             ; if-part
         (message "5 is greater than 4!"))   ; then-part

(The function `>' tests whether its first argument is greater than its
second argument and returns true if it is.)

   Of course, in actual use, the test in an `if' expression will not be
fixed for all time as it is by the expression `(> 5 4)'.  Instead, at
least one of the variables used in the test will be bound to a value
that is not known ahead of time.  (If the value were known ahead of
time, we would not need to run the test!)

   For example, the value may be bound to an argument of a function
definition.  In the following function definition, the character of the
animal is a value that is passed to the function.  If the value bound to
`characteristic' is `fierce', then the message, `It's a tiger!' will be
printed; otherwise, `nil' will be returned.

     (defun type-of-animal (characteristic)
       "Print message in echo area depending on CHARACTERISTIC.
     If the CHARACTERISTIC is the symbol `fierce',
     then warn of a tiger."
       (if (equal characteristic 'fierce)
           (message "It's a tiger!")))

If you are reading this inside of GNU Emacs, you can evaluate the
function definition in the usual way to install it in Emacs, and then
you can evaluate the following two expressions to see the results:

     (type-of-animal 'fierce)

     (type-of-animal 'zebra)

When you evaluate `(type-of-animal 'fierce)', you will see the
following message printed in the echo area: `"It's a tiger!"'; and when
you evaluate `(type-of-animal 'zebra)' you will see `nil' printed in
the echo area.

The `type-of-animal' Function in Detail
---------------------------------------

   Let's look at the `type-of-animal' function in detail.

   The function definition for `type-of-animal' was written by filling
the slots of two templates, one for a function definition as a whole,
and a second for an `if' expression.

   The template for every function that is not interactive is:

     (defun NAME-OF-FUNCTION (ARGUMENT-LIST)
       "DOCUMENTATION..."
       BODY...)

   The parts of the function that match this template look like this:

     (defun type-of-animal (characteristic)
       "Print message in echo area depending on CHARACTERISTIC.
     If the CHARACTERISTIC is the symbol `fierce',
     then warn of a tiger."
       BODY: THE `if' EXPRESSION)

   The name of function is `type-of-animal'; it is passed the value of
one argument.  The argument list is followed by a multi-line
documentation string.  The documentation string is included in the
example because it is a good habit to write documentation string for
every function definition.  The body of the function definition
consists of the `if' expression.

   The template for an `if' expression looks like this:

     (if TRUE-OR-FALSE-TEST
         ACTION-TO-CARRY-OUT-IF-THE-TEST-RETURNS-TRUE)

   In the `type-of-animal' function, the code for the `if' looks like
this:

     (if (equal characteristic 'fierce)
         (message "It's a tiger!")))

   Here, the true-or-false-test is the expression:

     (equal characteristic 'fierce)

In Lisp, `equal' is a function that determines whether its first
argument is equal to its second argument.  The second argument is the
quoted symbol `'fierce' and the first argument is the value of the
symbol `characteristic'--in other words, the argument passed to this
function.

   In the first exercise of `type-of-animal', the argument `fierce' is
passed to `type-of-animal'.  Since `fierce' is equal to `fierce', the
expression, `(equal characteristic 'fierce)', returns a value of true.
When this happens, the `if' evaluates the second argument or then-part
of the `if': `(message "It's tiger!")'.

   On the other hand, in the second exercise of `type-of-animal', the
argument `zebra' is passed to `type-of-animal'.  `zebra' is not equal
to `fierce', so the then-part is not evaluated and `nil' is returned by
the `if' expression.

If-then-else Expressions
========================

   An `if' expression may have an optional third argument, called the
"else-part", for the case when the true-or-false-test returns false.
When this happens, the second argument or then-part of the overall `if'
expression is _not_ evaluated, but the third or else-part _is_
evaluated.  You might think of this as the cloudy day alternative for
the decision `if it is warm and sunny, then go to the beach, else read
a book!".

   The word "else" is not written in the Lisp code; the else-part of an
`if' expression comes after the then-part.  In the written Lisp, the
else-part is usually written to start on a line of its own and is
indented less than the then-part:

     (if TRUE-OR-FALSE-TEST
         ACTION-TO-CARRY-OUT-IF-THE-TEST-RETURNS-TRUE
       ACTION-TO-CARRY-OUT-IF-THE-TEST-RETURNS-FALSE)

   For example, the following `if' expression prints the message `4 is
not greater than 5!' when you evaluate it in the usual way:

     (if (> 4 5)                             ; if-part
         (message "5 is greater than 4!")    ; then-part
       (message "4 is not greater than 5!")) ; else-part

Note that the different levels of indentation make it easy to
distinguish the then-part from the else-part.  (GNU Emacs has several
commands that automatically indent `if' expressions correctly.  See
GNU Emacs Helps You Type Lists.)

   We can extend the `type-of-animal' function to include an else-part
by simply incorporating an additional part to the `if' expression.

   You can see the consequences of doing this if you evaluate the
following version of the `type-of-animal' function definition to
install it and then evaluate the two subsequent expressions to pass
different arguments to the function.

     (defun type-of-animal (characteristic)  ; Second version.
       "Print message in echo area depending on CHARACTERISTIC.
     If the CHARACTERISTIC is the symbol `fierce',
     then warn of a tiger;
     else say it's not fierce."
       (if (equal characteristic 'fierce)
           (message "It's a tiger!")
         (message "It's not fierce!")))

     (type-of-animal 'fierce)

     (type-of-animal 'zebra)

When you evaluate `(type-of-animal 'fierce)', you will see the
following message printed in the echo area: `"It's a tiger!"'; but when
you evaluate `(type-of-animal 'zebra)', you will see `"It's not
fierce!"'.

   (Of course, if the CHARACTERISTIC were `ferocious', the message
`"It's not fierce!"' would be printed; and it would be misleading!
When you write code, you need to take into account the possibility that
some such argument will be tested by the `if' and write your program
accordingly.)

Truth and Falsehood in Emacs Lisp
=================================

   There is an important aspect to the truth test in an `if'
expression.  So far, we have spoken of `true' and `false' as values of
predicates as if they were new kinds of Emacs Lisp objects.  In fact,
`false' is just our old friend `nil'.  Anything else--anything at
all--is `true'.

   The expression that tests for truth is interpreted as "true" if the
result of evaluating it is a value that is not `nil'.  In other words,
the result of the test is considered true if the value returned is a
number such as 47, a string such as `"hello"', or a symbol (other than
`nil') such as `flowers', or a list, or even a buffer!

An explanation of `nil'
-----------------------

   Before illustrating a test for truth, we need an explanation of
`nil'.

   In Emacs Lisp, the symbol `nil' has two meanings.  First, it means
the empty list.  Second, it means false and is the value returned when a
true-or-false-test tests false.  `nil' can be written as an empty list,
`()', or as `nil'.  As far as the Lisp interpreter is concerned, `()'
and `nil' are the same.  Humans, however, tend to use `nil' for false
and `()' for the empty list.

   In Emacs Lisp, any value that is not `nil'--is not the empty
list--is considered true.  This means that if an evaluation returns
something that is not an empty list, an `if' expression will test true.
For example, if a number is put in the slot for the test, it will be
evaluated and will return itself, since that is what numbers do when
evaluated.  In this conditional, the `if' expression will test true.
The expression tests false only when `nil', an empty list, is returned
by evaluating the expression.

   You can see this by evaluating the two expressions in the following
examples.

   In the first example, the number 4 is evaluated as the test in the
`if' expression and returns itself; consequently, the then-part of the
expression is evaluated and returned: `true' appears in the echo area.
In the second example, the `nil' indicates false; consequently, the
else-part of the expression is evaluated and returned: `false' appears
in the echo area.

     (if 4
         'true
       'false)

     (if nil
         'true
       'false)

   Incidentally, if some other useful value is not available for a test
that returns true, then the Lisp interpreter will return the symbol `t'
for true.  For example, the expression `(> 5 4)' returns `t' when
evaluated, as you can see by evaluating it in the usual way:

     (> 5 4)

On the other hand, this function returns `nil' if the test is false.

     (> 4 5)